1. The Problem and the Options
Maven is a very versatile tool and its available public repositories are second to none. However there will always be an artifact that is either not hosted anywhere, or the repository where it is hosted is risky to depend on, as it may not be up when you need it.
When that happens, there are a few choices:
- bite the bullet and install a full fledged repository management solution such as Nexus
- try to get the artifact uploaded into one of more reputable public repositories
- install the artifact locally using a maven plugin
Nexus is of course the more mature solution, but it’s also the more complex. Provisioning an instance to run Nexus, setting up Nexus itself, configuring and maintaining it may be overkill for such a simple problem as using a single jar. If this scenario – hosting custom artifacts – is a common one however, a repository manager makes a lot of sense.
Getting the artifact uploaded into a public repository or in Maven central directly is also a good solution, but usually a lengthy one. In addition, the library may not be Maven enabled at all, which makes the process that much more difficult, so it’s not a realistic solution to being able to use the artifact NOW.
That leaves the third option – adding the artifact in source control and using a maven plugin – in this case, the maven-install-plugin to install it locally before the build process needs it. This is by far the easiest and most reliable option available.
2. Install Local Jar With the maven-install-plugin
Let’s start with the full configuration necessary to install the artifact into our local repository:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-install-plugin</artifactId>
<version>3.1.2</version>
<configuration>
<groupId>org.somegroup</groupId>
<artifactId>someartifact</artifactId>
<version>1.0</version>
<packaging>jar</packaging>
<file>${basedir}/dependencies/someartifact-1.0.jar</file>
<generatePom>true</generatePom>
</configuration>
<executions>
<execution>
<id>install-jar-lib</id>
<goals>
<goal>install-file</goal>
</goals>
<phase>validate</phase>
</execution>
</executions>
</plugin>
Now, let’s break down and analyze the details of this configuration.
The Artifact Information is defined as part of the <configuration> element. The actual syntax is very similar to declaring the dependency – a groupId, artifactId and version elements.
Next part of the configuration requires defining the packaging of the artifact – this is specified as jar.
Next, we need to provide the location of the actual jar file to be installed – this can be an absolute file path or it can be relative, using the properties available in Maven. In this case, the ${basedir} property represents the root of the project, namely the location where the pom.xml file exists. This means that the someartifact-1.0.jar file needs to be placed in a /dependencies/ directory under the root.
Finally, there are several other optional details that can be configured as well.
2.2. The Execution
The execution of the install-file goal is bound to the validate phase from the standard Maven build lifecycle. As such, before attempting to compile – you will need to run the validation phase explicitly:
mvn validate
After this step, the standard compilation will work:
mvn clean install
Once the compile phase does execute, our someartifact-1.0.jar is correctly installed in our local repository, just as any other artifact that may have been retrieved from Maven central itself.
2.3. Generating a POM vs Supplying the POM
The question of whether we need to supply a pom.xml file for the artifact or not depends on mainly on the runtime dependencies of the artifact itself. Simply put, if the artifact has runtime dependencies on other jars, these jars will need to be present on the classpath at runtime as well. With a simple artifact that should not be a problem, as it will likely have no dependencies at runtime (a leaf in the dependency graph).
The generatePom option in the install-file goal should suffice for these kinds of artifacts:
<generatePom>true</generatePom>
However, if the artifact is more complex and does have non-trivial dependencies, then, if these dependencies are not already in the classpath, they must be added. One way to do that is by defining these new dependencies manually in the pom file of the project. A better solution is to provide a custom pom.xml file along with the installed artifact:
<generatePom>false</generatePom>
<pomFile>${basedir}/dependencies/someartifact-1.0.pom</pomFile>
This will allow Maven to resolve all dependencies of the artifact defined in this custom pom.xml, without having to define them manually in the main pom file of the project.
3. Using Maven Commands
In this section, let’s learn how to use Maven commands to install a local jar. We’ll discuss the installation and usage of the jar in a simple project.
3.1. Setup JAR
First, let’s start by looking at the file structure for our library project using the exa command:
$ exa --tree .
.
├── com
│ └── baeldung
│ └── HelloWorld.java
└── manifest.txt
We can note that the library project contains a single HelloWorld.java file and a manifest.txt file.
Now, let’s see the hello() method in the HelloWorld class:
$ cat com/baeldung/HelloWorld.java
package com.baeldung;
public class HelloWorld {
public static void hello() {
System.out.println("Hello, world!");
}
public static void main() {
hello();
}
}
Next, let’s compile the HelloWorld.java file to generate the HelloWorld class and update the manifest.txt file:
$ javac com/baeldung/HelloWorld.java
$ cat manifest.txt
Main-Class: com.baeldung.HelloWorld
Lastly, we’re ready to package our library file in the HelloWorld.jar file:
$ jar cvfm HelloWorld.jar manifest.txt com/baeldung/HelloWorld.class
added manifest
adding: com/baeldung/HelloWorld.class(in = 479) (out= 320)(deflated 33%)
3.2. Install HelloWorld.jar
Now that we’ve got the jar file, we’ll use the mvn install:install-file command to install it in the local repository:
$ mvn install:install-file \
-Dfile=HelloWorld.jar \
-DgroupId=com.baeldung \
-DartifactId=hello-world \
-Dversion=1.0 \
-Dpackaging=jar
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- install:3.1.0:install-file (default-cli) @ standalone-pom ---
[INFO] pom.xml not found in HelloWorld.jar
[INFO] Installing /Users/tavasthi/baeldung/bael-2601/my-lib/HelloWorld.jar to /Users/tavasthi/.m2/repository/com/baeldung/hello-world/1.0/hello-world-1.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.160 s
[INFO] Finished at: 2023-06-14T17:38:18+05:30
[INFO] ------------------------------------------------------------------------
We must note that we didn’t have a pom.xml for our library project, so we’ve provided the groupId, artifactId, version, and packaging information using the -D option.
Further, let’s use the exa command to verify that the jar file is installed in the local .m2 repository:
$ exa --tree ~/.m2/repository/com/baeldung/hello-world
/Users/tavasthi/.m2/repository/com/baeldung/hello-world
├── 1.0
│ ├── _remote.repositories
│ ├── hello-world-1.0.jar
│ └── hello-world-1.0.pom
└── maven-metadata-local.xml
Great! We’ve got this one right. Additionally, we can also see that the command generated a pom.xml file as well.
3.3. Using HelloWorld.jar in a Project
To use the project, let’s create the my-project Maven project using the mvn command:
$ mvn archetype:generate \
-DgroupId=com.baeldung \
-DartifactId=my-project \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false
Now, let’s use the exa command to see the directory structure of our project:
$ exa --tree my-project
my-project
├── pom.xml
└── src
├── main
│ └── java
│ └── com
│ └── baeldung
│ └── App.java
└── test
└── java
└── com
└── baeldung
└── AppTest.java
Next, let’s add the hello-world dependency in the project’s pom.xml file:
<dependency>
<groupId>com.baeldung</groupId>
<artifactId>hello-world</artifactId>
<version>1.0</version>
</dependency>
Moving on, let’s call the hello() method from our library in our target project:
public class App
{
public static void main( String[] args )
{
com.baeldung.HelloWorld.hello();
}
}
Finally, let’s see this in action by running our target project:
$ mvn clean install && mvn exec:java -Dexec.mainClass="com.baeldung.App"
[INFO] Scanning for projects...
[INFO]
[INFO] ----------------------< com.baeldung:my-project >-----------------------
[INFO] Building my-project 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- exec:3.1.0:java (default-cli) @ my-project ---
Hello, world!
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.232 s
[INFO] Finished at: 2023-06-14T17:42:31+05:30
[INFO] ------------------------------------------------------------------------
Fantastic! We can see that the hello() method was executed successfully.
4. Conclusion
This article goes over how to use a jar which is not hosted anywhere within a Maven project by installing it locally with the maven-install-plugin. Additionally, we used the maven commands to setup and install a local jar, followed by using it in a target project.
